OMNIMONXL (TM)
USER'S GUIDE
by
David Young, CDY Consulting-
SYSTEM REQUIREMENTS: ATARI 800XL Home Computer
*** ATARI and ATARI 800XL Home Computer are trademarks of ATARI, Inc.
*** OMNIMONXL ' is a trademark of CDY Consulting.
*** OMNIMONXL program and manual contents Copyright 1984 CDY Consulting
AUTHOR'S EARNEST ENTREATY
I have done my best to offer here a quality program at a reasonable
price. This is my livelihood. Please do not make copies of this program
for any reason other than personal backup. Thank you.
INTRODUCTION
Greetings fellow ATARI Home Computer owner. I am sure you are just
as proud of your system as I am of mine and enjoy buying accessories to
extend its power and convenience. From that point of view, OMNIMONXL is
one of the most powerful additions you can make to your computer. Any
serious ATARI owner will find it indispensable after using it for the
first time.
OMNIMONXL is a resident machine language monitor which, once
installed, is always available to you. What that means is that you never
have to load it and you can call it up no matter what program happens to
be running at the time. Once running, OMNIMONXL gives you complete
control over your computer. This includes the ability to easily examine
and modify memory or the 6502's registers, to dump data to a printer,
and to read and write to the disk drive(s) without DOS. It also has a
complete set of debugging tools including a disassembler, single step,
and a unique JSR function for testing out subroutines. And all of these
features are available to you at any time, no matter what program is
running, simply by pressing SYSTEM RESET along with either the
OPTION/SELECT or SELECT button!
If you have been wanting to learn assembly \ language programming,
OMNIMONXL can make it a very pleasant experience. Since it is ROM
resident, you can always get back to OMNIMONXL even if your program
hangs up in an infinite loop or if the system is locked up. You can even
call OMNIMONXL at critical points in your program to examine things
before continuing execution.
GETTING STARTED
After installing RAMROD XL in your computer (if you have not done
so, see RAMROD XL INSTALLATION INSTRUCTIONS), • you should be able to
powerup your computer as usual. To enter the OMNIMONXL program, hold
down the OPTION/SELECT keys (press OPTION and SELECT simultaneously) and
press SYSTEM RESET. This method of entering OMNIMONXL will cause a
OMNIMONXL USER'S GUIDE
page 1
warmstart up to the point that the application program would normally be
given control. Instead OMNI MON.XL : ; "ontrol and you should see the
OMNIMONXL header written across '\hz -lip o: the screen:
David Young OMNIMONXL (6)1984
PC NV-BDIZC AC X Y SP
AF24D 73 00 09 3F IFF
The contents of the CPU registers are printed, in this case reflecting
the state of the RESET sequence of the OS rather than that of the
application program. Later we will discuss another method of entering
OMNIMONXL which preserves the PC and CPU registers of the application
program. VThen you are ready to exit OMNIMONXL, hold down the START
button and type RETURN. This will cause the warmstart to go to
completion, giving control back to the application program.
There are a few important things to point out before proceeding:
1) All numerical input and output is done in hex.
2) Parameters are delimited by a space or other non-hex character.
3) The command being processed will be aborted if an illegal parameter
is encountered or if a necessary parameter is not supplied.
4) It is not necessary to retype a command if it is already present on
the screen. Just position the cursor on the same line, make changes
if you wish, and type RETURN. All th<r normal ATARI editing commands
are available.
5) The processing of most commands can be stopped by holding down the
START button. This allows you to terminate a long listing, search or
single step. Use CTRL-1 to temporarily halt and restart a listing.
DISPLAY MEMORY: D (start addr) (end addr)
This command is used to view data in memory in either hex or
character format, depending on the current data format (see TOGGLE). In
hex format the data is output to the screen as 1 or more lines of 8 hex
bytes separated by spaces. In character format the data is output as 1
or more lines of 24 byte character strings. On each line, the address of
the first byte precedes the data.
In either data format the letter 'A* is appended to the start of
each line. This in fact represents the ALTER MEMORY command (see the
following command description). The effect is that, once you have used
'D' to display part of memory, you can alter any byte(s) by simply
positioning the cursor, typing the change(s), and hitting RETURN. You
must type RETURN on each line that you alter fpr the change to take
effect. Also, the current data format must match the way the data was
represented on the line. One other limitation in the character mode is
that a line containing the character representing $9B is not alterable
past that character. If you wish to alter a line after a S9B character,
redisplay the line starting just past it.
OMNIMONXL USER'S GUIDE
page 2
To display memory, type 'D' followed by optional start and . stop
addresses. You can display up to 32K bytes (S8000) with one command. If
you omit the stop address, only a single line of data will be printed.
If you omit the start address, the next logical line of data will be
printed (either the next 8 or 24 bytes of memory, depending on the data
format). One last convenience is that once you have used the 'D'
command, OMNIMONXL will default to that command if you just type RETURN.
This allows you to scroll through memory by holding down the RETURN key.
This default will remain in effect until one of the other 'persistent'
commands (R or X) are used, at which time they will become the default.
TOGGLE DATA FORMAT: T
As mentioned previously, all numerical data is represented in hex.
However, when dealing with ASCII text it is more convenient to work in
character format. The TOGGLE command (T) is used to switch between hex
and character format. It affects three commands: ALTER MEMORY (A),
DISPLAY MEMORY (D) and SEARCH MEMORY (S). Other commands are unaffected
by the current data format.
To switch data formats type 'T' (RETURN). Upon first entering
OMNIMONXL the data type defaults to hex.
ALTER MEMORY: A addr byte byte ...
This command is used to change 1 or more contiguous bytes of
memory. You can type the change either as hex bytes (separated by
spaces) or as ATASCII character strings, depending on the current data
format (see TOGGLE). While it is possible to use the 'A' command by
itself at any time, it is not recommended. To display the area of memory
first with the 'D' command and then to position the cursor and make the
change is much safer (see DISPLAY MEMORY). This way you not only verify
that the memory at that location is the memory you intended to change,
but also that the current data format is compatible with the data you
are typing.
To use the ALTER MEMORY command, type 'A' followed by an address.
Use a space to separate the address and the data and then start typing
the data. If in hex format, type hex bytes delimited by spaces. If in
character format, type a continuous character string. Terminate the
command with RETURN. At that point the indicated changes will be made.
The command line can be as long as you like or until the computer
squawks .
SEARCH MEMORY: S addr byte byte ...
Searching is something that computers do very well and OMNIMONXL
has a very nice search function that works in either hex or character
mode. It will scan memory for any sequence you specify and display it in
a manner similar to the DISPLAY MEMORY command every time it is found.
This means you can alter any occurrence of that sequence by simply
positioning the cursor, typing the change and hitting RETURN (see
DISPLAY MEMORY).
To use the SEARCH MEMORY command, type 'S' followed by the address
OMNIMONXL USER'S GUIDE
page 3
where you would like the search to begin. Then type a space followed by
the search sequence. This will be hex bytes separated by spaces in hex
mode or a character string in character mode (see TOGGLE). The search
will begin when you hit RETURN. The search sequence can be any length up
to the limit of the ATARI terminal input buffer. Even though it only
takes a few seconds to search all of memory, a search can be aborted by
holding down the START button.
Hex Conversion/Arithmetic: H = (■=• oper) (= oper) ...
This is a versatile command for converting hex to decimal and vice
versa. It will also do hex arithmetic by allowing you to specify an
additional hex number followed by an operand. The operands are + (add),
- (subtract), * (multiply), and / (divide). For example, say you wanted
to calculate the number of single density sectors required to write an
8K block of memory to disk:
H C000 A000 - 80 /
SC000=49152
$2000=2048
$0040=64
Wl A000 40
SC000 is first converted to decimal, then SA000 is subtracted and the
difference is printed out, and finally the result is divided by S80 and
the quotient is printed out.
The rules of the Hexadecimal Arithmetic command are:
1) The first number may be in hex or decimal with a decimal number
terminated by a non-hex character (i.e., 256T=$100).
2) Every number after the first must be in hex. If you need to use a
decimal number, convert it to hex first.
3) The divide operand (/) rounds down for fractions less than .5 and up
for fractions greater than .5.
PRINTER ON/OFF: P
If you want a hardcopy record of your OMNIMONXL session, you can
use the '?' command to cause anything being output to the screen to be
echoed to the printer. In character mode, inverse video characters are
printed as normal video and unprintable characters are translated to
dashes (-). Otherwise, everything on the screen will show up on the
printer. There is even a special single step mode (see EXECUTE) that
will trace through a program while outputting only to the printer and
not to the screen. This is useful for programs that use screen modes
other than GRAPHICS 0.
The 'P' command is a toggle function. Typing it once will enable
output to the printer and typing it again will disable output. If the
printer is not turned on or selected, the message 'I/O ERROR ' will
result. Care should be taken if the printer is enabled while reading or
writing to the disk (see READ DISK or WRITE TO DISK).
OMNIMONXL USER'S GUIDE
page 4
The trace turned on by the P command can be redirected to any
output device. If it is desired to output to something other than the
printer, store the device specification someplace in memory and point
ST25 (PBUFAD) to that location. The P command will then open up an I/O
channel to that device and the next P command will close it. For
example, if you were to store ' D : TEMP ' (notice the blank used as a
terminator) at $600 and store 00 06 at $125, the P command would open up
a disk file (assuming of course that an FMS is in memory).
DISK INPUT/OUTPUT
Anyone who owns my disk utility DISKSCAN knows how useful it is to
be able to edit raw sector data on a disk-. One of my goals in designing
0MNIM0NXL was to incorporate some of the features of DISKSCAN. Imagine,
a resident mini-DISKSCAN !
Well, the end result has far exceeded my expectations. With
OMNIMONXL you can not only read and write individual sectors, but
multiple sectors to and from anywhere in memory. And it not only works
in sequential mode, but it can also follow sector links. In fact, you
can read in an entire DOS file from a disk without even booting up DOS!
And the frosting on the cake is that OMNIMONXL works equally well in
single or double density, a dream come true for the growing number of
double density drive owners.
LINK/SEQ MODE & DRIVE = : L (drive-)
When you first enter OMNIMONXL, the program assumes that you wish
to talk to drive fM and that the sector mode is sequential. If you wish
to address other drives or follow sector links, use the LINK command to
put OMNIMONXL in the correct mode. The LINK command is actually two
commands in one. When used by itself (without a parameter) 'L' means to
toggle from sequential to linked mode or vice versa. When followed by a
drive = (1-4), 'L* means to switch the drive ID to the specified drive.
From that point on, all disk I/O will be directed to that drive.
To toggle between the sequential and linked sector modes, type 'L
(RETURN)'. To direct disk I/O to a different drive, type 'L' followed by
the drive = and RETURN.
READ DISK: R (sector=) (buffer addr) (= sectors)'
The READ DISK command is one of the most powerful, user friendly
functions of OMNIMONXL. It can be used to read one or more sectors,
either sequentially or linked, from any disk drive, single or double
density. We will start out by using the READ DISK command to read one
sector at a time. You will find it behaves somewhat differently when
operating on more than one sector at a time.
To read a single sector into memory type 'R' followed by the sector
-, buffer address and RETURN. From that point on OMNIMONXL will assume
that buffer address for subsequent disk I/O. Once you have the sector in
memory you can operate on it with any of the other OMNIMONXL commands
including DISPLAY, ALTER, SEARCH, DISASSEMBLE, etc. One convenient
feature is that, after a READ DISK command, OMNIMONXL will assume the
OMNIMONXL USER'S GUIDE
page 5
buffer address if you use 'D' or 'X' without a start address. (Try
typing 'D (RETURN ) ' after reading a sector into memory).
Now, if you wish to read the sector which logically follows the
last sector read into memory, type 'R (RETURN) 1 . In sequential mode, the
next physical sector on the disk will be read. In linked mode, OMNIMONXL
will reference the sector link of the current sector to determine the
next sector to read. In either case, the new sector will be read into
memory at the SAME buffer address, overlaying the old sector.
NOTE: IF THE PRINTER IS ENABLED WHILE READING SINGLE SECTORS, THE SECTOR
= AND BUFFER ADDRESS MUST BE SPECIFIED EACH TIME. This is because the
printer and disk share the SIO DCB (Device Control Block).
Ready for a couple more examples of user friendliness? One is that
the 'R' command, like 'D'and 'X', is a 'persistent' command. That means
that once you use the 'R' command, OMNIMONXL will default to that
command if you just type RETURN. This default will remain in effect
until one of the other persistent commands are used. What this means is
that you can read through an entire file (or disk, if in sequential
mode) by reading the first sector and then simply holding down the
RETURN key. One other convenience is that OMNIMONXL will not read past
the end of file if it is in linked mode. Thus, if you were reading
through a file as suggested above, simply hold down the RETURN key until
'EOF' is printed. At that point, the last sector of the file is at the
buffer address. You are free to add something to the end of the file
(perhaps an autorun vector) and then to write the sector back out with
the WRITE SECTOR command.
Reading multiple sectors is somewhat different from reading single
sectors. For one thing, the sector =, buffer address, and sector count
must be specified each time. The other difference is that, instead of
consecutive sectors overlaying each other, the bufier address is
incremented between sectors so that the disk data fills memory. The
exact amount by which the buffer address is incremented depends on the
sector mode and the density of the drive. The effect is that in
sequential mode all bytes of the sector are preserved, while in linked
mode the sector links are overlayed. This is a desirable feature if you
want to read an entire DOS file into memory.
An example may be of help. First, put OMNIMONXL in character mode
with 'T' and sequential mode with 'L'. Now type 'R 169 6000 8'. This
will read in the 8 sectors of the directory into the buffer at $6000.
Now type 'D' followed by several RETURNS. You will be able to read the
names of the files on the disk. Choose the filename of a short file, put
OMNIMONXL in hex mode with 'T', and use 'D addr' to display the 5 bytes
just prior to the filename. The first byte is the status while the next
two are the size of the file and the next two are the start sector. (You
can more easily determine the start sector and file size with the 'G'
command.) Now put the program in linked mode with 'L'. Read in the
entire file with *R (start sector) 6000 (file size)'. Type 'D' and hold
down the RETURN key to scroll through the data of the file.
One final convenience is that each time a single sector is read,
its = is printed along with the buffer address. This also occurs when
OMNIMONXL USER'S GUIDE
page 6
multiple sectors are l-ead, but only when the printer is on or if you
hold down the OPTION switch during the operation. Thus, if you read in
an entire file with the printer on, you get a sector map of that file.
Now if, while inspecting the file in memory, you find that you wish to
make a change to the file on disk, you can compare the buffer address to
the sector map of the file to determine the sector where that piece of
data resides. Then you can use 'R sec=' to fetch that sector, make the
change, and use 'W sec=' to store the sector back on disk.
For those of you with Happy drives, there is one extra feature
which you may find handy. If a Happy drive is read. or written to with a
sector = of S800 or greater, the Happy drive treats the sector = as an
internal buffer address ( S800-$ 1 3FF ) . On multiple reads or writes the
sector - is incremented by $80 each sector. Usage of the RAM buffer is
as follows (compliments of David Milligan of Surrealistic Software):
S800-SA7F - RAM area for program uploading, as in programming the
drive to do something.
SA80-SAFF - RAM area used by the onboard O.S. as a scratchpad
area. Used for pointers, flags, etc.
SB00-S13FF -RAM area for track reads and writes.
WRITE TO DISK: W (sector =) (buffer addr) (= sectors)
The WRITE TO DISK command allows you to write one or more sectors
worth of memory out to disk. The one big difference between it and the
READ DISK command is that it only works in the sequential mode. That
means that it will not create a DOS file, i.e., it will create neither a
directory entry nor sector links. If you do wish to create a DOS file
out of memory it is best to use the BINARY SAVE option of DOS. However,
it is not always possible to get DOS into memory without losing your
data. In this case, OMNIMONXL may be the only way save your data. If you
do wish to create a DOS file out of the memory you have written to disk
with OMNIMONXL, use the technique described under the 'G' command.
IMPORTANT: Use a scratch disk when writing multiple sectors worth of
memory to disk with OMNIMONXL. The program pays no attention to data
already on the disk and may overlay it.
The primary purpose of the WRITE TO DISK command is to support the
modification of one sector at a time. A typical scenario is as follows:
Turn the printer on, read a file into memory as described in READ
DISK, and turn the printer off. Search the file to find the data to
be changed. Compare the address of the data in memory to the sector
map created while the file was being read in. Read that particular
sector into memory with 'R sec-'. This insures that you not only
have the data of the sector but also the sector link. Then alter
the sector and write it back out with 'W sec =l .
Be careful when omitting the sector P because the default has already
been incremented in anticipation of the next READ DISK. In fact, the
only safe time to omit the sector - is when that sector is the last one
of a linked file.
OMNIMONXL USER'S GUIDE
page /
Binary Load / Directory: G (file spec) (addr)
The versatility and convenience of this command is really quite
amazing. First of all, it will load any binary load file from a single
or double density ATARI DOS compatible disk (2. OS, 2. OP, MYDOS , OSA+2.0,
etc.). This includes files that even DOS cannot load because they load
on top of it. Secondly, as it searches the disk directory for the
specified file, it prints out the filenames, file sizes and start
sectors in hex. For example, put a disk with a binary load file into
drive =1. Now type:
G D:filename
Pretty nice. Here are the rules for using 'G':
1) The file specification is similar in format to that of DOS. For
example, ' D : FILE ' , '1:FILE', and 'FILE' all are equivalent to
•D1 : FILE ' .
2) If you do not give a file specification, 'G' will search the
directory and not find a match but in the process will print out the
entire directory. Thus 'G(RETURN)' will give the directory of drive
=1 while 'G2: (RETURN) ' yields the directory of drive =2.
3) Another nice feature of 'G' is that it will print out the load
vectors of a binary load file if you hold down the OPTION key while
the file is being loaded. It will print out each load vector and
pause before it loads the data to satisfy that load vector. Pressing
SELECT will load the data and print the next load vector. If you wish
to terminate the load, press START. Try loading several birary load
files while holding down the OPTION key and you will be surprised at
how complicated some of them are (the ATARI Macro Assembler for
instance ) .
4) One final option concerns the sector buffer address which 'G' uses
while it is loading the file. If you do not specify an address, S400
is the default. If the binary file happens to load into this area
(S400-47F for single density or $400-$4FF for double), you may
specify another buffer address in hex which does not interfere with
the load.
By the way, once the binary load has started, 'G' uses zero page
locations $43-49. These are locations reserved for use by DOS, in
particular during a binary load. Thus, 'G' should load anything that the
'L' option of DOS does. However, some files may not load correctly if
you use the console switches as described in rule =3 above because the
resources used to print out the load vectors may interfere with the load
itself.
Once you have a binary load file in memory you can create a boot
disk by switching over to sequential mode and writing the program back
out to a disk starting at sector 1. You will need to leave 6 overhead
bytes at the beginning of the first sector. See the ATARI OPERATING
SYSTEM USER'S MANUAL for details on the boot process.
OMNIMONXL USER'S 3UIDE
page 8
The converse of this process would be to create a binary load file
from a boot record. This can be done by first booting up DOS, going to
OMNIMONXL, and reading in the boot record in sequential mode to a
convenient place in memory. Then you would exit back to DOS and do a
BINARY SAVE on that portion of memory. Then you may have to use
OMNIMONXL to change the load vector at the beginning of the file to make
it load in at the correct place. In fact, you may have to use OMNIMONXL
to load the file if it loads on top of DOS. The same technique can be
used to make a binary load file out of a cartridge but you will have to
append a few load vectors to get the program going. For example, the
following 3 load vectors should be appended to the end of BASIC: 6A 00
6A 00 90 E2 02 E3 02 F6 F3 E0 02 El 02 00 AO.
How do you go about appending these load vectors? One easy way to
add a few bytes to the end of a file is as follows:
1 ) Find the last sector of. a file by determining the start sector,
putting OMNIMONXL into the linked mode, reading it into memory with
the 'R' command and holding down RETURN until 'EOF' is printed out.
2) Determine the last data byte of the sector by looking at the byte
count (the last byte of the sector).
3) Just past the last data byte add the new bytes. Then increase the
byte count to reflect the appended bytes and write the sector back
out with 'W(return)'.
If you find this discussion confusing, read the tutorial on binary
load files at the end of this document.
SEVERAL WAYS TO ENTER OMNIMONXL
We have seen how to enter OMNIMONXL by holding down OPTION/SELECT
and pressing SYSTEM RESET. This causes a normal warmstart followed by a
jump subroutine (JSR) to OMNIMONXL. When you exit OMNIMONXL after
entering it in this way (by holding down START and pressing RETURN) , the
warmstart goes to completion in a normal fashion. This is fine for some
applications, but there is another way to enter OMNIMONXL which disturbs
the program running as little as possible.
When you hold down SELECT and press SYSTEM RESET, the program
running at the time is interrupted. However, instead of doing the entire
warmstart, parts of it are skipped over so as to preserve the state of
the system as much as possible. Specifically, the OS variables and the
stack are left undisturbed. Usually this allows you to reenter the
program by simply exiting OMNIMONXL in the normal fashion. For instance,
you can pop into OMNIMONXL from either DOS or BASIC, execute some
OMNIMONXL commands, and pop back into the interrupted program almost as
if you had never left it. I say 'almost' because the OS is likely to
return a bogus value if it was waiting for a keystroke when it was
interrupted. For that reason it is best to hit BREAK upon return to the
program. Of course, if the program makes use of any graphics other than
MODE 0, it is unlikely that you will be able to successfully reenter the
program without restarting it. This is also true of programs which alter
the interrupt RAM vectors ($200-3224) because OMNIMONXL restores them to
their original values.
OMNIMONXL USER'S GUIDE
page 9
There are a couple of small problems with using SELECT/RESET
(instead of OPTION/SELECT/RESET) to interrupt DOS or BASIC. OMNIMONXL
makes use of the SIO interrupt routines in the OS ROM by altering the
interrupt vectors at $20A-$20D. This is so the printer and disk
interface of OMNIMONXL will work even if DOS is not in memory. Now if
you return back to DOS with START/RETURN these interrupt vectors will
remain in effect. But DOS hangs up occasionally unless it is using its
own special SIO handlers. If you wish DOS to restore its special
vectors, exit OMNIMONXL with SYSTEM RESET. Another problem with
SELECT/RESET is that MEMLO ($2E7) gets restored to $700 so that the FMS
or any other program in low memory is unprotected. For that reason, it
is best to exit OMNIMONXL back to BASIC with RESET. Alternatively,
always use OPTION/SELECT/RESET to enter OMNIMONXL from BASIC.
Another way to enter OMNIMONXL is particularly useful for debugging
assembly language programs. This is accomplished by putting 'JSR SCOOV
at critical points within the program. At each of these points OMNIMONXL
will be entered and you will have all of its facilities available for
examining the intermediate results of your program. When you are ready
to continue executing your program, just exit OMNIMONXL with
START/RETURN. There are some restrictions on this technique however,
specifically special graphics and time critical I/O.
Yet another way to enter OMNIMONXL is from BASIC with a
'X=USR(49152) ' . You can exit back to BASIC in the usual manner
(START/RETURN) .
It should also be pointed out that OMNIMONXL will be entered
automatically if a 6502 BRK instruction (0) is >;ver executed. Thus, you
can set a breakpoint anywhere in your program by storing a 0. When you
pop into OMNIMONXL after executing a BRK instruction, you should restore
the original instruction and subtract 2 from the PC. Now you can
continue executing your code when you exit OMNIMONXL.
CPU REGISTERS: C
You will notice that, upon entering OMNIMONXL, the 6502' s internal
registers are printed out with the following heading:
PC NV-BDIZC AC X Y SP
The meanings of those headings are pretty self-explanatory except
for 'NV-BDIZC. These are the individual bits of the status register
spelled out. Thus, this is a snapshot of the state of the CPU just prior
to entering OMNIMONXL. The PC (program counter) is pointing to the next
instruction to be executed. The program will continue executing at this
point when you leave OMNIMONXL with START/RETURN.
The CPU state can be examined at any time with the CPU REGISTERS
command 'C. In addition, the CPU state can be changed by simply
positioning the cursor over the value, typing the change, and hitting
RETURN. The new values for the registers will be in effect when you
leave OMNIMONXL to resume execution of the suspended program. The only
CPU register that cannot be changed directly is the stack pointer. This
can be changed only by the PUSH STACK (+) and POP STACK (-) commands.
OMNIMONXL USER'S GUIDE
page 10
One application for the 'C command is to GOTO anyplace in memory.
This is accomplished by altering the PC to point to the address where
you wish execution to resume when you press START/RETURN. Typically this
might be back to DOS, whose address can usually be found by looking in
location SOOOA (DOSVEC).
Another area of interest is the stack. Remember, the stack pointer
always points to the next FREE entry. All the values between the stack-
pointer and S1FF are typically return addresses of nested subroutine
calls. This, in fact, is a vertical cross section of the execution
history of the program. This is extremely useful for finding your way
around in a program you wish to modify in some way. If you wish to to
locate the part of a program which is performing a certain function,
just start the program executing that function and press SELECT/RESET.
Because the stack is preserved with this method of entering OMNIMONXL,
you can tell where the program is and where it has been by noting the PC
and the return addresses on the stack. Another way of locating a certain
piece of code is to search ('S') for a particular address it might
reference .
PUSH STACK: + byte byte ...
The PUSH STACK command is for adding bytes to the stack^and thereby
increasing the stack pointer (which grows downward in the 6o02). These
bytes will be available to the code pointed to by the PC when OMNIMONXL
is exited. Notice that the first byte after ' + ' is the first one to be
pushed onto the stack.
Please note that the stack pointer displayed with the ' C command
is not the ACTUAL stack pointer while OMNIMONXL is running. OMNIMONXL
uses the stack for its own purposes and is actually nested somewhat
deeper. It is not wise to make changes directly to the stack unless you
use PUSH STACK or POP STACK.
POP STACK: -
The POP STACK command takes bytes off of the stack one at a time
and decreases the stack pointer (which actually increases in value).
DISASSEMBLE MEMORY: X (start addr) (stop addr)
Just as it is possible to display memory in hex or character
format, it is also possible to translate 6502 machine code to assembly
language. OMNIMONXL does this in a handy fashion by printing out the
object code along with the instruction. Once again, it is possible to
change the object code (to the left of '*') by positioning the cursor,
typing the change, and hitting RETURN. Another convenience is that the
value at the address specified with indirect addressing modes (without
regard to the index register) is printed in parentheses.
Just like the *R' and 'D' commands, 'X' is 'persistent'. Once you
have disassembled one or more instructions, you can continue
disassembling simply by holding down RETURN. This will remain in effect
until 'R' or 'D' are used. The disassembler can be aborted at any time
by pressing the START button.
OMNIMONXL USER'S GUIDE
page 1 1
Assembler: Y addr instruction
This will not take the place of your 2 pass assembler. 'Y' is a
line assembler, meaning that you type in a line of assembly language and
it will convert it to machine code immediately. If you have ever had to
hand patch 6502 object code you will know how handy this function can
be. It saves you from having to look up the opcodes in a table. Also,
sometimes it is desirable to write a quicky routine to try something
out. For example, say you wanted to see what the key codes are that get
stored in location $2FC whenever you press a key. To do so you could
type in the following commands:
Y 600 LDA $2FC (get key code)
CMP r*$FF
BEQ $600 (no key pressed?)
STA $610 (store new key code)
RTS
(just hit RETURN to terminate assembler)
Notice that you need to type 'Y addr' only once. From that point on the
assembler will prompt you for the next instruction. To execute this
routine :
J 600
(START/RETURN)
(press a key)
D 610 (to see what the key code is)
Here are the rules of the assembler:
1) To enter the assembler, type 'Y addr ir.ntruc tion ' where 'addr' is the
starting address in hex and * instruci ion ' is a legal 6502 assembly
language instruction.
2) To exit the assembler just type RETURN when prompted for the next
instruction .
3) If you want to make a change to an assembly language instruction
which is already on the screen, just move the cursor up to that
instruction (it must be the line with the 'Y' at the beginning), make
the change, and hit RETURN. This is valid whether or not you are
currently in the assembler.
4) When specifying operands, hex numbers are preceded by '$' and decimal
numbers are not.
5) Branch instructions (BEQ, BNE, etc.) are handled quite easily. The
operand can be specified as an absolute address (in hex or decimal)
and the assembler will calculate the displacement. Or, if you prefer,
you can specify a displacement oreceded by + or -. Thus, in the
example above, the 'BEQ $600» could be replaced by 'BEQ -5' with the
same result.
OMNIMONXL USER'S GUIDE
page 12
EXECUTE MEMORY: E (option/- steps)
The EXECUTE MEMORY command is actually a single step command in
disguise ('S' is used for SEARCH). This command causes the instruction
pointed to by the PC to be executed. Then the registers are printed out
along with the NEXT instruction to be executed. If the step count was 1
(or not specified) then execution will stop. Otherwise it will continue
single stepping through the code for the specified =■ steps. The maximum
number of steps at one time is 31 for reasons soon to become clear.
While the low order 5 bits of the optional parameter are a step
count, the high order 3 bits have special meaning. The MSB means 'step
forever'. Thus, ' E 80' means 'step forever and print the trace to the
screen'. Notice that the trace will also be echoed to the printer if it
is enabled. Stepping can be aborted by pressing START.
Bit 6 of the parameter means 'don't print the trace to the screen'.
However, the trace will still be output to the printer if it is enabled.
Thus, 'E CO' would step forever without printing the trace to the
screen. In combination with the printer this is useful for stepping
through programs which use special graphics modes.
Bit 5 of the parameter means 'sample the results of every 32
instructions'. Thus, 'E E0' would step forever without printing to the
screen and the trace would be output to the printer every 32nd
instruction (if it is enabled). This is kind of a weird mode, but
somebody may find a use for it someday.
One other nice feature of the 'E' command is that it will treat a
call to the OS as a single instruction instead of stepping through all
the code in the OS. OMNIMONXL does this by temporarily giving up control
of the CPU but intercepting it on the return from the OS. However, you
should avoid stepping through CIO calls to the screen editor (E:) unless
printing to the screen is disabled with bit 6. OMNIMONXL considers any
address above SC000 to be OS.
We have seen that the EXECUTE MEMORY command is very powerful and
versatile. One restriction, however, is that it will not step through a
'SEI' instruction. If you are stepping through a program and encounter a
SEI, disassemble on past it to find the 'CLI'. Just past the CLI put a
temporary BRK instruction (0). Now step through the SEI. OMNIMONXL will
temporarily lose control of the program but will regain it when the BRK
instruction is executed. Now restore the original value to the location
where the BRK was set. After subtracting 2 from the PC you are ready to
continue stepping.
JSR: J addr
The JSR command is a very powerful feature for executing a
subroutine and returning control back to OMNIMONXL. It can be used for
testing out subroutines during the development of an assembly language
program. With some care it can also be used to call the OS to, say,
format a disk.
When you execute the 'J' command you will notice that the registers
OMNIMONXL USER'S GUIDE
page 13
are printed out but that the subroutine is not yet executed. In fact,
the 'J' command does nothing more than change the PC to the specified
address and push the address of OMNIMONXL on the stack to act as the
return address for the subroutine. Now you are free to set up for the
subroutine call by altering the registers or memory if necessary. When
you are ready to actually execute the subroutine press START/RETURN.
Upon return you will notice that the PC is restored to its original
value but that the other registers reflect the results of the
subroutine .
As an example, put a fresh disk (or one you don't mind formatting)
in drive 1. With the printer disabled, store a 1 in $301, a $21 in $302,
and a $80 in $303. Now execute a 'J E453' and press START/RETURN. The
disk in drive 1 will be formatted and then control will be returned to
OMNIMONXL.
Sometimes after interrupting a program with OMNIMONXL, you will not
be able to restart it without reinitializing it. The start and
initialization addresses for a program are typically at S000A and S000C
respectively. Since a proper initialization routine is always a
subroutine, you can use 'J (init addr)' to initialize the program. When
control returns to OMNIMONXL, you need only change the PC to the start
address and exit OMNIMONXL with START/RETURN to restart the program.
Move Memory: M addrO addrl addr2
This command is for moving blocks of code fron: anywhere in memory
to anywhere in RAM. It matters not if the source ar.d destination blocks
overlap. The move command is very simple to use. Just supply the
following addresses:
addrO = source start address
addrl = source end address
addr2 = destination start address
For example, say you have the following code located at $600 (you can
use the 'Y' command to enter it):
$600 LDA $2FC
$603 CMP -$FF
$605 BEQ $600
$607 STA $60D
$60A JMP S60E
$60D NOP
$60E RTS
I know this is a dumb program but I wish to make a point. To move
the code to $620, type: M 600 60E 620. Now use 'X' to disassemble the
code at $620 and you will recognize it as the same. Now, unless the code
were relocatable, you would not be able to run the code at the new
location without adjusting some of the absolute addresses. Which
addresses? The ones which reference locations within the address space
of the program. The 'STA $60D' and 'JMP $60E' would both have to be
adjusted. That is the purpose of the Relocate command ('N'), to be
described next.
OMNIMONXL USER'S GUIDE
page 14
Verify Memory: V addrO addrl addr2
Compare 2 blocks of memory and print differences. The first block
starts at addrO and ends at addrl. The second block starts at addr2.
Notice that the parameters were designed to complement the move command!
For example, if you just moved some code with 1 M ' , you can verifv the
move by simply changing the • M ' to a 'V and hitting RETURN.
Relocate 6502 Code: N addrO addrl addr2 (addr3) (addr4)
Relocate will adjust code assembled to run in one location so that
it will execute in another. The format is as follows:
addrO = start of addr reference range to be adjusted
addrl = end of addr reference range to be adjusted
addr2 = new base addr -
addr3 = start addr of code to be adjusted (default: addr2)
addr4 = end addr of code to be adjusted
(default: addr3+[addrl-addr0] )
This command was designed to be very versatile but, because it has
so many options, it can be quite confusing. However, since it was also
designed to complement the ' M ' command, its use usually requires no
thinking at all. Specifically, in the example above we used ' M 600 60E
620' to move the code from S600-60E to $620. Because it has absolute
memory references to the range of S600-60E, the copy at $620 will not
execute properly. If we now move the cursor back up to the ' M ' command
and change the ' M ' to an 'N' ('N 600 60E 620') and hit RETURN, the code
at $620 will be adjusted to run at $620. Try it and then disassemble the
code at $620. Notice the absolute memory references to the range of
$600-60E have been adjusted to reflect the new base address of $620.
Now, say we wanted to adjust the code at S600-60E so that it will
run at $700 but we don't want to move there to do it (perhaps you did
not want to wipe out DOS, which starts at $700). In this case we must
specify addr3 and addr4 as follows:
N 600 60E 700 600 60E
Notice that addr0,1 & 2 are the same as if you had moved the code to
$700 first CM 600 60E 700') but that addr3 & 4 tell »N' that the code
physically resides at $600-60E. After execution of the above command the
code at $600-60E disassembles to this:
$600 LDA $2FC
$603 CMP ^$FF
S605 BEQ $600
$607 STA $70D
$60A JMP $70E
S60D NOP
$60E RTS
Notice that the reference to $2FC is not modified because it is outside
the address range specified by addx-0,1. Also, don't worry about 'BEQ
$600' because it is relocatable.
OMNIMONXL USER'S GUIDE
page 15
Before you try relocating a big program like a cartridge, let me
point out that it will probably still take considerable work. The ' N '
command cannot differentiate between 6502 instructions and imbedded
program data. The only thing it can do is stop if it hits an illegal
opcode and this may or may not be soon enough to avoid modifying some
data it should not have (data that happened to look like 6502 code with
absolute address references). It also cannot do anything about indirect
references to the address range of addr0,1 (for example, indirect
references to a data table imbedded within the program). Likewise, jump
tables will not be adjusted. The data tables should be easy to locate
and move with the ' M ' command. The indirect references will probably be
more difficult to find and adjust. The jump tables will have to' be
adjusted by hand. Thus, the ' N ' command is most easily used to move
relatively small routines around.
Although big programs may present a problem, I will give one other
example to show how versatile the Relocate command really is. Say you
wanted to move a routine from one part of a program to another. Not only
would you have to relocate the routine but you would also have to use
the 'N' command on the rest of the program to adjust any references to
that routine. Say you had the following program:
S600 LDA $604, X (start of routine)
$603 RTS
$604-607 (imbedded data table)
$608 LDX =3 (this is start of program)
$60A JSR $600
$60D STA $D001 ,X
$610 DEX
$611 BNE $60A
$613 RTS
You would like to move the routine and associated data table from $600
to S614. The following commands will do this:
M 600 607 614 (move little routine and table)
N 600 607 614 608 617 (relocate entire program)
After these commands the program should look like this:
$608 LDX -3 (this is start of program)
$60A JSR $614
$60D STA $D001 ,X
$610 DEX
$611 BNE $60A
$613 RTS
$614 LDA $618, X (start of routine)
$617 RTS
$618-61B (imbedded data table)
Study this example carefully. If you understand it completely then
you have mastered the 'N' command. You will find it (along with ' Y ' , 1 M '
and 'X') a big help in patching programs for which you don't have source
code or don't want to take the time to reassemble.
OMNIMONXL USER'S GUIDE
page 16
Fill Program Buffer: F addr
If you find yourself using a certain sequence of OMNIMONXL commands
frequently, you may want to program the monitor to execute them
automatically. Likewise, if you are debugging or analyzing a program,
you may want the monitor to remember the sequence of commands so that
you can duplicate them at a later time. The *F addr' command tells
OMNIMONXL to start saving all your commands at the specified address
(the program buffer). It will continue to save your commands until you
execute an 'FO' to tell it to quit. Then the '0 addr' command is used to
execute from the program buffer at any later time.
The format of the ' F' command is as follows:
F addr - 'addr' can be any non-ZPAGE address in RAM. It will
enter the program mode at this point, remembering
all subsequent commands. An addr of terminates
the program mode.
The program buffer should be a place in memory that will not
interfere with anything else you are doing. As long as you are in the
program mode the ASCII data stored in the buffer will continue to grow,
eventually wiping out everything in its path if you forget to terminate
the program mode with ' FO 1 .
Since the data stored in the program buffer is ASCII text, you may
edit it if you wish. Just remember that the program data must be
terminated with a hex 0. Also, if you wish to enter the program mode and
append to the end of the current data rather start over, you may do so
as follows:
T (to get into character mode)
S addr FO ( addr=program buffer; find 'FO')
A xxxx FO (which previously exited program mode)
F xxxx (start filling buffer at that location)
One slight annoyance you will encounter in the program mode is that
the result of the 'T' command depends on the the current mode (char or
hex). If you use the 'T' command as part of the programmed sequence you
will want to force one mode or the other at the beginning of the
sequence so that you will always get the same results no matter what
mode you happen to be in when you execute the sequence later. It is
possible to force the hex mode with the following sequence :' A98 0'.
If the data of your command buffer is of any importance you may
want to back it up occasionally to a scratch disk. This could be done as
follows :
1) Find the 'FO* at the end of the buffer as in the example above and
add 3 to determine the end address.
2) Subtract the start address from the end address and divide by the
sector size to determine the number of sectors to write.
3) Write that number of sectors off to a scratch disk with the MV*
command. Be sure to include the buffer terminator, hex 0.
OMNIMONXL USER'S GUIDE
page 17
Restoring a previously saved buffer is as easy as reading the
sectors back into memory with the ' R ' command. If the command sequence
is of lasting importance, you may want to create a binary load file by
going to DOS and doing a BINARY SAVE on the command buffer. The ' g "'
command may then be used to fetch it at any time.
Operate from program buffer: addr
This command is used to execute OMNIMONXL commands stored as ASCII
text somewhere in memory (and terminated with a hex 0). The format is as
follows:
addr - 'addr' is the address of the OMNIMONXL commands stored
as ASCII text.
Upon execution of the '0' command, the display editor ( E : ) device
vector at location $321 is replaced with a pointer into a special
handler in OMNIMONXL which takes its input from the program buffer
(which is pointed to by $98, COMPTR) instead of the keyboard. It will
continue to do so until the command interpreter hits a hex in the
program buffer, at which point input it will revert back to the
keyboard .
One thing you will notice when using the '0' command is that only
the results of the commands are printed, not the commands themselves. If
you need to see the commands also, turn on the printer with 'P' prior to
executing '0'. The commands will show up on the hardcopy.
Boot Disk
Boot off of the drive selected with *L'. You can boot off of a
drive other than drive =1 only if it is a single stage boot.
Binary Load Files
This is one area that most people are a little fuzzy on. It's not
surprising really, since there does not appear to be any definitive
documentation on it anywhere! An exhaustive presentation will be made
here even though it will be quite short.
Definition: load vector - from 4 to 6 bytes consisting of 2 optional
bytes of FF FF, a 2 byte start address, and a 2 byte end
address (in that order).
Example: FF FF 00 06 02 06 - The first 2 bytes are optional and
ignored during the load process. The second 2 bvtes are a
start address of $600 and the last 2 bytes are an end
address of $602.
The only time that the first 2 bytes of FF FF are required is at
the beginning of a binary load file. If those bytes are not there, DOS
will refuse to perform the binary load. (The 'G' command of OMNIMONXL
will, however, load it gladly.) The rest of the time the first 2 bytes
of FF FF, if they exist, are ignored. The only time that these 2
optional bytes should occur anywhere else but at the beginning of a file
OMNIMONXL USER'S GUIDE
page 18
is if 2 binary load files were appended together.
What does a load vector do? It tells DOS (or the 'G' command of
OMNIMONXL) where in memory to put the 1 or more bytes which follow in
the file. How many bytes is determined by subtracting the start address
from the end address and adding 1. In the example above, 3 bytes would
be read from the file and put in locations $600 to $602.
What happens when enough bytes have been read in to satisfy a load
vector? These things will happen in this order:
1) Locations $2E2 and $2E3 will be examined. If they are both zero, goto
step 2. If they are nonzero, a JSR will be made to the address
contained in these locations. Upon return, zero $2E2 and S2E3 and
fall into step 2.
2) If the end of file is not reached (i.e., there are more bytes in the
file), another load vector is assumed to immediately follow and will
be processed as previously described.
3) If the end of file (EOF) is reached, examine locations $2E0 and $2E1.
If they are zero, terminate the binary load. If they are nonzero, do
a JSR to the address in these locations. Upon return, terminate load.
Still confused? Let me try to simplify. If you see a load vector
like 'E2 02 E3 02', you know that the subroutine at the address
specified in the following 2 bytes will get executed immediately, prior
to continuing the load process. If you see a load vector like 1 E0 02 El
02*, you know that the subroutine at the address in the following to 2
bytes will be executed after the end of file is reached.
Now that you understand everything there is to know about binary
load files, let's take a typical example: converting the BASIC cartridge
to binary load file. I use this example because it is instructive and,
because of the lack of copyright notice, appears to be legal. Using this
technique on other cartridges could be illegal and may not work anyway
due to the booby traps designed to prevent them from running out of RAM*.
Let's see what it takes to get the BASIC program to run out of RAM:
-Turn on the computer with BASIC installed and pop into OMNIMONXL.
-Insert a formatted scratch disk into the drive and execute the
following command: 'Wl A000 40 (RETURN)'.
-Remove the BASIC cartridge, boot up DOS and pop into OMNIMONXL.
-Because OMNIMONXL restores MEMLO to $700, we should reinitialize DOS
by doing a JSR to the address at DOSINI ($C,D). For 2. OS that would be
• J 1 540 ( RETURN ) ( START/RETURN ) ' .
-Move the screen down by storing a $90 in location $6A and doing a JSR
SF3F6: 'A 6A 90 (RETURN)',' J F3F6 (RETURN) (START/RETURN)'
-Read BASIC back into memory with 'Rl A000 40 (RETURN)*.
-Find the initialization address by looking at location $BFFE. Since
that is $BFF9 , execute »J BFF9 (RETURN) (START/RETURN)'.
-Find the start address by looking at location $BFFA. Since that is
SA000, execute ' J A000 (RETURN) (START/RETURN)'.
BASIC will now come up running. Now we want to create a binary load file
to simulate the last 4 steps:
OMNIMONXL USER'S GUIDE
page 19
-Type 'DOS' to get to the DOS menu.
-Use the 'K' command to save BASIC as a binary load file giving it the
start address of A00O and the end address of BFFF.
-Pop into OMNIMONXL and put it in linked mode. Read the first sector of
the new file into S6000 (see top of page 7 if you don't know how to
find the first sector of a file).
-Hold down RETURN until 'EOF' is printed out. You now have the last
sector of the file in memory.
-Determine the last byte of that sector in use by looking at the bvtc
count ($607F). Start adding the following bytes at location $6000* +
byte count (we are appending to the file):6A 00 6A 00 90 E2 02 E3 0?
F6 F3 00 98 08 98 20 06 98 6C FA BF 6C FE BF E0 02 El 02 00 98
-Increase the byte count (S607F) by $1E and write that sector back out
to the disk with 'W (RETURN)'.
Command Summary
Page -
3 Alter Memory: A addr byte byte ... - Used to change 1 or more
contiguous bytes of memory.
18 Boot Disk: B - Will boot off of the selected drive.
10 CPU Registers: C - Used to display and alter the registers
2 Display Memory: D (start addr) (end addr) - Used to view' memory
data. To alter memory, position cursor and type change.
13 Execute Memory: E (option/- steps) - Will execute one or more
instructions at a -time and display intermediate results
17 Fill Prgm Buffer: F addr - Teach monitor a sequence of commands
for later execution with the '0' command.
8- Get File: G (file spec) (addr) - A full binary load function
single or double density. Doubles as disk directory command.
4 Hex Arithmetic H = (- oper) (= dper) ... - Hex conversion allowing
addition, subtraction, multiplication and division.
13 Jump Subroutine: J (addr) - Go execute subroutine.
5 Link Drive: L (drv=) - Select drive = and linked or sequential
sector modes. All disk I/O will go to the selected drive
14 Move Memory: M addrO addrl addr2 - Move a block of memory from
anywhere in memory to anywhere else.
15 Relocate Memory: N addrO addrl addr2 (addr3) (addr4) - Adjust 650?
code that it will execute in another location.
18 Operate Prgm Buffer: O addr - Execute the commands stored earlier
with the 'F' command.
4 Printer Control: P - Screen I/O can be echoed to a printer
5 Read Disk: R (sect-) (buff addr) (= sects) - Read one 'or more
sectors from selected disk drive into a specified buffer area
3 Search Memory: S addr byte byte ... - Search memory for and'print
out occurrences of a sequence of bytes.
J v° g ?i e *, F ° rmat: T " T °Sgle between hex and 'character formats.
15 Verify Memory: V addrO addrl addr2 - Compare 2 blocks of memory
and print out the differences.
7 Write Disk: W (sect-) (buff addr) (^ sects) - Write one or more
sectors to disk from a specified buffer address.
11 Disassembler: X (addrO) (addrl) - Translate machine code into
assembly language. Can be used to create a source file
12 Assembler: Y addr instr - Translate assembly language ' into machine
code one line at a time. Useful for patching programs.
H
J
L
M
N
P
R
Y
OMNIMONXL USER'S GUIDE
page 20
